<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN">
<html>
<head>
<!-- 
  Copyright 2007 Timothy Wall
-->
</head>
<body bgcolor="white">
<HR>
<CENTER>
<H1>Java Native Access</H1>
</CENTER>
This document is the API specification for the
<a href="https://github.com/java-native-access/jna">JNA</a>
library for simplified native library access for Java.
<p>
<a href=#navbar_top>Top</a>&nbsp;
<a href="https://github.com/java-native-access/jna">JNA Home</a>&nbsp;
<a href=index.html target=_top>API w/FRAMES</a>&nbsp;
<p>

<a name="overview"></a>
<h1>Java Native Access (JNA)</h1>
JNA provides simplified access to native library methods without requiring any
additional JNI or native code.
<p>

<a name="toc"></a>
<h2>Table of Contents</h2>
<ul>
<li><a href="#loading">Loading JNA</a>
<li><a href="#library-mapping">Library Mapping</a>
<li><a href="#function-mapping">Function Mapping</a>
<li><a href="#marshalling">Type Mapping</a>
  <ul>
  <li><a href="#marshalling">Primitive Types</a>
  <li><a href="#pointers">Pointers</a>
  <li><a href="#strings">Strings</a>
  <li><a href="#wide-strings">Wide (UNICODE) Strings</a>
  <li><a href="#arrays">Primitive Arrays</a>
  <li><a href="#buffers">Buffers/Memory Blocks</a>
  <li><a href="#callbacks">Callbacks/Function Pointers</a>
  <li><a href="#varargs">Variable Argument Lists (Varargs)</a>
  <li><a href="#structures">Structures</a>
  <li><a href="#unions">Unions</a>
  <li><a href="#java-objects">Java Objects</a>
  <li><a href="#last-error">Last Error</a>
  </ul>
<li><a href="#invocation-mapping">Invocation Mapping</a>
<li><a href="#global-data">Library Global Data</a>
<li><a href="#crash-protection">VM Crash Protection</a>
<li><a href="#performance">Performance</a>
</ul>

<p>
<a href=#navbar_top>Top</a>
<a name="loading"></a>
<h2>Loading JNA</h2>
JNA includes a small, platform-specific shared library which enables all
native access.  When the {@link com.sun.jna.Native} class is first accessed,
JNA will first attempt to load this library from the directories specified
in <code>jna.boot.library.path</code>. If that fails and <code>jna.nosys=false</code>
is set, it will fall back to loading from the system library paths. Finally it
will attempt to extract the stub library from from the JNA jar file, and load it.
<p/>
The <code>jna.boot.library.path</code> property is mainly to support
jna.jar being included in -Xbootclasspath, where
<code>java.library.path</code> and LD_LIBRARY_PATH are ignored.  It is also
useful for designating a version of the library to use in preference to any
which may already be installed on the system.
<p/>
Loading from the system may be enabled by <code>jna.nosys=false</code>,
and unpacking from the jar file may be disabled by
<code>jna.nounpack=true</code>.
<p/>
The library name used to search for JNA's native library may be altered
by setting <code>jna.boot.library.name</code>, which defaults to
"jnidispatch".  It may be useful to set this value if your system
requires unique names for shared libraries (rather than unique paths),
or if your system must store different versions of the JNA shared
library (e.g. for different architectures) in the same directory.
<p/>

<a href=#navbar_top>Top</a>
<a name="library-mapping"></a>
<h2>Library Mapping</h2>
When you've determined which shared library holds the methods to which you
need access, create a class corresponding to that library.  For
example, a mapping for the C library itself would look like one of the
following:<br> 
<blockquote><code><pre>
// Alternative 1: interface-mapped class, dynamically load the C library
public interface CLibrary extends Library {
    CLibrary INSTANCE = (CLibrary)Native.load("c", CLibrary.class);
}

// Alternative 2: direct-mapped class (uses a concrete class rather than an
// interface, with a slight variation in <a href="#direct-mapping">method
// declarations</a>). 
public class CLibrary {
    static {
        Native.register("c");
    }
}
</pre></code></blockquote>
The <code>String</code> passed to the
{@link com.sun.jna.Native#load(String,Class)}
(or {@link com.sun.jna.NativeLibrary#getInstance(String)}) method
is the undecorated name of the shared library file.  Here are some examples of
library name mappings.<p>  
<style type="text/css">
table.styled { border-collapse:collapse; background-color:#EAEAEA; }
td { padding-left: 10px; padding-right: 10px; }
blockquote { background-color:#EAEAEA; }
</style>
<table border=1 borderColor=white class=styled>
<tr><th><b>OS</b></th><th><b>Library Name</b></th><th><b>String</b></th></tr>
<tr><td>Windows</td><td>user32.dll</td><td>user32</td></tr>
<tr><td>Linux</td><td>libX11.so</td><td>X11</td></tr>
<tr><td>Mac OS X</td><td>libm.dylib</td><td>m</td></tr>
<tr><td>Mac OS X Framework</td><td>/System/Library/Frameworks/Carbon.framework/Carbon</td><td>Carbon</td></tr>
<tr><td>Any Platform</td><td>&lt;current process&gt;</td><td><code>null</code></td></tr>
</table>
<p>
Any given native library with a unique filesystem path is represented by a single instance of {@link com.sun.jna.NativeLibrary} and obtained via {@link com.sun.jna.NativeLibrary#getInstance(String)}.  The native library will be unloaded when no longer referenced by any Java code.
<p>
If the library name is <code>null</code>, your mappings will apply to the
current process instead of a separately loaded library.  This may help avoid
conflicts if there are several incompatible versions of a library available.
<p>
The search path for loaded native libraries may be modified by
setting <code>jna.library.path</code> and a few other properties.  You may
also bundle native libraries in a jar file and have JNA automatically extract
them for loading.  See {@link com.sun.jna.NativeLibrary} for details. 
<p>
<a href="#toc">Table of Contents</a>
<a name="function-mapping"></a>
<h2>Function Mapping</h2>
Function names are mapped directly from their Java interface name to the
symbol exported by the native library.  For instance, the function to convert
an ASCII string into an integer would look like this:<br>
<blockquote><code><pre>
public interface CLibrary extends Library {
    int atol(String s);
}
</pre></code></blockquote>
<a name="direct-mapping"></a>
Alternatively, you can map directly to a declared native method 
(with <a href="https://github.com/java-native-access/jna/blob/master/www/DirectMapping.md">some restrictions</a>):<br>
<blockquote><code><pre>
public class CLibrary {
    public static native int atol(String s);
}
</pre></code></blockquote>

If you prefer to rename the Java methods to conform to Java coding conventions, then you can provide an entry ({@link com.sun.jna.Library#OPTION_FUNCTION_MAPPER}/{@link com.sun.jna.FunctionMapper}) in the options {@link java.util.Map} passed to {@link com.sun.jna.Native#load(String,Class,java.util.Map) Native.load()} which maps the Java names to the native names.  While this keeps your Java code a little cleaner, the additional mapping of names may make it a little less obvious the native functions being called.<p>
An instance of the {@link com.sun.jna.Function} class is obtained through the {@link com.sun.jna.NativeLibrary} instance corresponding to the containing native library.  This {@link com.sun.jna.Function} instance handles argument marshalling and delegation to the native function. 

<p>
<a href="#toc">Table of Contents</a>
<a name="marshalling"></a>
<h2>Marshalling/Unmarshalling (Java/Native Type Conversions)</h2>
Java types must be chosen to match native types of the same size.  Following are the types supported by the JNA library.<p>
<center>
<table border=1 borderColor=white class=styled width="100%">
<tr><th><b>C Type</b></th><th><b>Native Representation</b></th><td><b>Java Type</b></th></tr>
<tr><td>char</td><td>8-bit integer</td><td>byte</td></tr>
<tr><td>wchar_t</td><td>platform-dependent</td><td>char</td></tr>
<tr><td>short</td><td>16-bit integer</td><td>short</td></tr>
<tr><td>int</td><td>32-bit integer</td><td>int</td></tr>
<tr><td>int</td><td>boolean flag</td><td>boolean</td></tr>
<tr><td>enum</td><td>enumeration type</td><td>int (usually)</td></tr>
<tr><td>long long, __int64</td><td>64-bit integer</td><td>long</td></tr>
<tr><td>float</td><td>32-bit floating point</td><td>float</td></tr>
<tr><td>double</td><td>64-bit floating point</td><td>double</td></tr>
<tr><td>pointer (e.g. void*)</td><td>platform-dependent (32- or 64-bit pointer to memory)</td><td>{@link java.nio.Buffer}<br>
{@link com.sun.jna.Pointer}</td></tr>
<tr><td>pointer (e.g. void*),<br>array</td><td>32- or 64-bit pointer to memory (argument/return)<br>contiguous memory (struct member)</td><td>&lt;P&gt;[] (array of primitive type)</td></tr>
<tr><td colspan='3'  style='padding:20px 5px'>In addition to the above types, which are supported at the native layer, the JNA Java library automatically handles the following types.  All but <code>NativeMapped</code> and <code>NativeLong</code> are converted to {@link com.sun.jna.Pointer} before being passed to the native layer.</td></tr>
<tr><td>long</td><td>platform-dependent (32- or 64-bit integer)</td><td>{@link com.sun.jna.NativeLong}</td></tr>
<tr><td>const char*</td><td>NUL-terminated array (native encoding or <code>jna.encoding</code>)</td><td>{@link java.lang.String}</td></tr>
<tr><td>const wchar_t*</td><td>NUL-terminated array (unicode)</td><td>{@link com.sun.jna.WString}</td></tr>
<tr><td>char**</td><td>NULL-terminated array of C strings</td><td>{@link java.lang.String String[]}</td></tr>
<tr><td>wchar_t**</td><td>NULL-terminated array of wide C strings</td><td>{@link com.sun.jna.WString WString[]}</td></tr>
<tr><td>void**</td><td>NULL-terminated array of pointers</td><td>{@link com.sun.jna.Pointer Pointer[]}</td></tr>
<tr><td>struct*<br>struct</td><td>pointer to struct (argument or return) ({@link com.sun.jna.Structure.ByReference or explicitly})<br>struct by value (member of struct) ({@link com.sun.jna.Structure.ByValue or explicitly})</td><td>{@link com.sun.jna.Structure}</td></tr>
<tr><td>union</td><td>same as <code>Structure</code></td><td>{@link com.sun.jna.Union}</td></tr>
<tr><td>struct[]</td><td>array of structs, contiguous in memory</td><td>{@link com.sun.jna.Structure Structure[]}</td></tr>
<tr><td>void (*FP)()</td><td>function pointer (Java or native)</td><td>{@link com.sun.jna.Callback}</td></tr>
<tr><td>pointer (&lt;T&gt; *)</td><td>same as <code>Pointer</code></td><td>{@link com.sun.jna.PointerType}</td></tr>
<tr><td>other</td><td>integer type</td><td>{@link com.sun.jna.IntegerType}</td></tr>
<tr><td>other</td><td>custom mapping, depends on definition</td><td>{@link com.sun.jna.NativeMapped}</td></tr>
</table>
</center>
<p>
<b>NOTES</b>
<ul>
<li>Unsigned values may be passed by assigning the corresponding
  two's-complement representation to the signed type of the same size.  
<li>Java arrays of primitive type may be wrapped by {@link java.nio.Buffer} in
  order to access a subset of the array (changing the effective size and/or
  offest).
<li>Java arrays of primitive type and non-direct {@link java.nio.Buffer}s are only valid for use within the scope of a
  single call.  If the native code keeps a reference to the memory, use {@link
  com.sun.jna.Memory} or direct {@link java.nio.ByteBuffer}s instead.
<li>Primitive arrays and structures as members of a structure are overlaid on the parent structure memory.  
<li>Bitfields must be manually packed into an integer type.  
<li>All other types must eventually be converted to one of the types in the this table.  Methods with arguments or return values of types other than these must either use types deriving from {@link com.sun.jna.NativeMapped} or supply type conversion information for the unsupported types.  
<li>Type mapping behavior may be customized by providing a {@link com.sun.jna.TypeMapper} for the {@link com.sun.jna.Library#OPTION_TYPE_MAPPER} option when initializing a library interface.  See {@link com.sun.jna.win32.W32APITypeMapper} for an example which provides custom conversion of boolean and String types.  You are free to use whatever types are convenient in your defined interfaces, but all custom types <em>must</em> provide a mapping to one of the basic or derived types listed above.
<li>Type mapping may also be customized on a per-class basis for user-defined types by making the user-defined type implement the {@link com.sun.jna.NativeMapped} interface.  
<li><code>Structure</code> and <code>Union</code> are <em>not</em> converted to <code>Pointer</code> when passed by value.
</ul>

<a name="arrays"></a>
<h3>Primitive Arrays</h3>
Java primitive arrays may be used wherever a native primitive array is used.  Any changes made by the native code to an array during a function call will be reflected in the Java array.  If the native code will use the array outside of the function call where the array is provided, {@link com.sun.jna.Memory} or {@link java.nio.Buffer} should be used instead (see <a href="#buffers">Buffers</a>).
<p>
To map a native multi-dimensional array, use a single-dimensional Java array with a number of elements equivalent to the full native array, e.g.<br>
<blockquote><code><pre>
// Original C code
#define DIM0 2
#define DIM1 3
int array[DIM0][DIM1];
int i,j;

for (i=0;i &lt; DIM0;i++) {
  for (j=0;j &lt; DIM1;j++) {
    array[i][j] = i*DIM1 + j;
  }
}

// Equivalent JNA code
final int DIM0 = 2;
final int DIM1 = 3;
int[] array = new int[6];
for (int i=0;i &lt; DIM0;i++) {
  for (int j=0;j &lt; DIM1;j++) {
    array[i*DIM1 + j] = i*DIM1 + j;                   
  }                   
}
</pre></code></blockquote>

<a name="pointers"></a>
<h3>Pointers</h3>
Pointers may be used as an opaque type from which other data types may be extracted.  The Pointer type is a reasonable fallback for any pointer-based type (including arrays).  The user is generally not allowed to construct a Pointer de novo. 
<p>
Type-safe pointers may be defined by deriving from the {@link com.sun.jna.PointerType} class.  Any such user-defined type will be treated the same as a {@link com.sun.jna.Pointer}.

<a name="strings"></a>
<h3>Strings</h3>
Java <code>String</code>s perform the same function as the native types
<code>const char*</code> and <code>const wchar_t*</code>
(<code>NUL</code>-terminated arrays).  In order to use the proper type when
calling a native function, we have to introduce some sort of annotation to
identify how the java  <code>String</code> should be converted.

Java <code>String</code>s are normally converted to <code>char*</code>
since this is the most common usage of strings.  Strings are automatically
converted to a <code>NUL</code>-terminated array of <code>char</code> across
the function call.  Returned <code>char*</code> values are automatically
copied into a <code>String</code> if the method signature returns
<code>String</code> (<code>strdup</code>, for example).
<p>
If the native method returns char* and actually allocates
memory, a return type of {@link com.sun.jna.Pointer} should be used to avoid
leaking the memory.  It is then up to you to take the necessary steps to free
the allocated memory.
<p>
When converting Java unicode characters into an array of <code>char</code>,
the default platform encoding is used, unless the system property
<code>jna.encoding</code> is set to a valid encoding.  This property may be
set to "UTF8", for example, to ensure all native strings use that encoding.
<p>
Arrays of <code>String</code> passed to native code (either as a function argument or callback return value) will be converted into a NULL-terminated array of <code>char*</code> (or <code>wchar_t*</code> in the case of an array of <code>WString</code>.

<a name="wide-strings"></a>
<h3>Wide Strings</h3>
The {@link com.sun.jna.WString} class is used to identify wide character strings.  Unicode values are copied directly from the Java <code>char</code> array to a native <code>wchar_t</code> array.
<p>

<a name="buffers"></a>
<h3>Buffers/Memory Blocks</h3>
Use arrays to represent buffers of primitive types passed to a function for use only during the function invocation.  If the native code
keeps a pointer to the memory after the native function returns, use direct {@link java.nio.ByteBuffer}s or {@link com.sun.jna.Memory} instead.
<p>A native method cannot return a Java array, since there is no canonical way to indicate the intended length of the returned array.
Instead, use one of the array access methods in the Pointer class, supplying the length of the returned array.<p>
{@link java.nio.Buffer}s may also be used as a memory buffer input
argument; direct byte buffers can often provide much improved performance over
primitive arrays.
A pointer provided by native code may be converted to a {@link java.nio.Buffer} by calling {@link com.sun.jna.Pointer#getByteBuffer}.
<p>
If you need to pass in a subset of a primitive array, you can do so by
wrapping it in a {@link java.nio.Buffer} subclass, such as {@link
java.nio.ByteBuffer}, using the {@link
java.nio.ByteBuffer#wrap(byte[],int,int)} method.  Wrapping an array in a
buffer also allows you to pass only a subset of a Java array to the native
function. 

<a name="callbacks"></a>
<h3>Callbacks (Function Pointers)</h3>
JNA supports supplying Java callbacks to native code.  You must define an
interface that extends the {@link com.sun.jna.Callback} interface, and define
a single <code>callback</code> method with a signature that matches the
function pointer required by the native code.  The name of the method
may be something other than "callback" only if there is only a single method
in the interface which extends Callback or the class which implements
{@link com.sun.jna.Callback}.  The arguments and return value follow the same
rules as for a direct function invocation. 
<p>
When accessing Windows APIs, sometimes the documentation indicates that a
function pointer parameter must refer to a function that resides in a 
DLL.  In these instances, add the {@link com.sun.jna.win32.DLLCallback}
interface to your callback definition.  The function pointer as seen by
Windows will be located in the <code>jnidispatch.dll</code> module.
<p>
If the callback returns a <code>String</code> or <code>String[]</code>, the
returned memory will be valid until the returned object is GC'd.
<p>
If your native code initializes function pointers within a struct, JNA will
automatically generate a <code>Callback</code> instance matching the declared
type.  This enables you to easily call the function supplied by native code
using proper Java syntax.
<blockquote><code><pre>
// Original C code
struct _functions {
  int (*open)(const char*,int);
  int (*close)(int);
};

// Equivalent JNA mapping
public class Functions extends Structure {
  public static interface OpenFunc extends Callback {
    int invoke(String name, int options);
  }
  public static interface CloseFunc extends Callback {
    int invoke(int fd);
  }
  public OpenFunc open;
  public CloseFunc close;
}
...
Functions funcs = new Functions();
lib.init(funcs);
int fd = funcs.open.invoke("myfile", 0);
funcs.close.invoke(fd);
</pre></code></blockquote>

Callbacks may also be used as return values.  Native function pointers are wrapped in a proxy implementing the declared Callback type, to facilitate calling from Java.  
<blockquote><code><pre>
// Original C code
typedef void (*sig_t)(int);
sig_t signal(int signal, sig_t sigfunc);

// Equivalent JNA mapping
public interface CLibrary extends Library {
    public interface SignalFunction extends Callback {
        void invoke(int signal);
    }
    SignalFunction signal(int signal, SignalFunction func);
}
</pre></code></blockquote>

If you need control over the thread context in which a <code>Callback</code>
operates, you can install a {@link com.sun.jna.CallbackThreadInitializer} for
any given callback object.  The first time the callback is called on a thread
that is not currently attached to the VM, the initializer will be queried to
determine how the thread should be set up.  You can indicate the desired name,
thread group, and daemon state for the thread, as well as indicating whether
the thread should be left attached to the VM after callback exit.  The latter
improves performance if you know you will be getting multiple callbacks on the
same thread, avoiding the need for the VM to generate multiple Java Thread
objects for the same native thread.  If you do leave the native thread
attached, you should either ensure you detach it at some later point (by
calling {@link com.sun.jna.Native#detach} from within the callback just prior
to return) or return true from your
{@link com.sun.jna.CallbackThreadInitializer#isDaemon(Callback)} method so
that the native thread will not prevent the VM from exiting.<p/>
If you don't need to otherwise customize the callback thread, you can simply
call {@link com.sun.jna.Native#detach(boolean)} from within your callback to
indicate whether the thread attachment should be maintained or not.<p/>

<a name="varargs"></a>
<h3>Varargs</h3>
The C varargs function definition may be mapped to a Java varargs method definition.  For example,
<blockquote><code><pre>
// Original C code
extern int printf(const char* fmt, ...);

// Equivalent JNA mapping
interface CLibrary extends Library {
    int printf(String fmt, ...);
}
</pre></code></blockquote>

<em>Varargs are not supported when using <a href="https://github.com/java-native-access/jna/blob/master/www/DirectMapping.md">Direct mapping</a>.</em>

<a name="structures"></a>
<h3>Structures</h3>

The Java {@link com.sun.jna.Structure} represents a native <code>struct</code>.  By default, this type is treated as a pointer to structure (<code>struct *</code>) on the native side when used as a parameter or return value.  When used as a structure field, the structure is interpreted as by value.  To force the complementary interpretation, the tagging interfaces {@link com.sun.jna.Structure.ByValue} and {@link com.sun.jna.Structure.ByReference} are provided.<p>

The data within a Java <code>Structure</code> is automatically written to
native memory just before a native function call with a struct parameter, and
automatically read from native memory after the function returns.<p>

<h4>Pointer-to-Structure Arguments</h4>
To pass a pointer to a structure as an argument, simply use the Java structure
subclass, and a pointer to native data memory will be used.  The contents of
the structure will be passed to the function and updated when the function
returns.  Structures are packed according to the default alignment rules for
the platform's native C <code>struct</code>s.  
<blockquote><code><pre>
// Original C code
typedef struct _Point {
  int x, y;
} Point;

Point* translate(Point* pt, int dx, int dy);

// Equivalent JNA mapping
class Point extends Structure { public int x, y; }
Point translate(Point pt, int x, int y);
...
Point pt = new Point();
Point result = translate(pt, 100, 100);
</pre></code></blockquote>

<a name="byvalue"></a>
<h4>Structure by Value Arguments/Return</h4>
To pass a structure by value, first define the structure, then define an empty
class from that which implements {@link com.sun.jna.Structure.ByValue}.  Use
the <code>ByValue</code> class as the argument or return type.<p>
<blockquote><code><pre>
// Original C code
typedef struct _Point {
  int x, y;
} Point;

Point translate(Point pt, int dx, int dy);

// Equivalent JNA mapping
class Point extends Structure {
    public static class ByValue extends Point implements Structure.ByValue { }
    public int x, y;
}
Point.ByValue translate(Point.ByValue pt, int x, int y);
...
Point.ByValue pt = new Point.ByValue();
Point result = translate(pt, 100, 100);
</pre></code></blockquote>


<h4>Array-of-Structure Arguments</h4>
To pass an array of structures, simply use a Java array of the desired
structure type.  If the array is uninitialized, it will be auto-initialized
prior to the function call.<p>
<blockquote><code><pre>
// Original C code
void get_devices(struct Device[], int size);

// Equivalent JNA mapping
int size = ...
Device[] devices = new Device[size];
lib.get_devices(devices, devices.length);
</pre></code></blockquote>

Alternatively, you can reallocate a single Structure instance into an array as
follows:<br>
<blockquote><code><pre>
Device dev = new Device();
// As an array of Structure
Structure[] structs = dev.toArray(size);
// As an array of Device
Device[] devices = (Device[])dev.toArray(size);
</pre></code></blockquote>

<h4>Returning an Array of <code>struct</code></h4>
Declare the method as returning a {@link com.sun.jna.Structure} of the
appropriate type, then invoke {@link com.sun.jna.Structure#toArray(int)} to
convert to an array of initialized structures of the appropriate size.  Note
that your {@link com.sun.jna.Structure} class must have a no-args constructor,
and you are responsible for freeing the returned memory if applicable in
whatever way is appropriate for the called function.<p>
<blockquote><code><pre>
// Original C code
struct Display* get_displays(int* pcount);
void free_displays(struct Display* displays);

// Equivalent JNA mapping
Display get_displays(IntByReference pcount);
void free_displays(Display[] displays);
...
IntByReference pcount = new IntByReference();
Display d = lib.get_displays(pcount);
Display[] displays = (Display[])d.toArray(pcount.getValue());
...
lib.free_displays(displays);
</pre></code></blockquote>

<h4>Nested Structure Definitions</h4>
Nested structures are treated as consecutive memory (as opposed to pointers to
structures).  For example:<br>
<blockquote><code><pre>
// Original C code
typedef struct _Point {
  int x, y;
} Point;

typedef struct _Line {
  Point start;
  Point end;
} Line;

// Equivalent JNA mapping
class Point extends Structure {
  public int x, y;
}

class Line extends Structure {
  public Point start;
  public Point end;
}
</pre></code></blockquote>

Explicit initialization of nested structures is not required; the objects will
be created as needed and properly mapped to the parent structure's memory.<p>

If you need a pointer to a structure within your structure, you can use the
{@link com.sun.jna.Structure.ByReference} tagging interface to indicate the
field should be treated as a pointer instead of inlining the full structure.
<blockquote><code><pre>
// Original C code
typedef struct _Line2 {
  Point* p1;
  Point* p2;
} Line2;

// Equivalent JNA mapping
class Point extends Structure {
    public static class ByReference extends Point implements Structure.ByReference { }
    public int x, y;
}
class Line2 extends Structure {
  public Point.ByReference p1;
  public Point.ByReference p2;
}
</pre></code></blockquote>

The more general case is just a pointer to memory.  This allows you to define
the field without necessarily defining the inner structure itself, similar to
declaring a struct without defining it in C:<br>

<blockquote><code><pre>
// Original C code
typedef struct _Line2 {
  Point* p1;
  Point* p2;
} Line2;

// Equivalent JNA mapping
class Line2 extends Structure {
  public Pointer p1;
  public Pointer p2;
}

Line2 line2;
Point p1, p2;
...
line2.p1 = p1.getPointer();
line2.p2 = p2.getPointer();
</pre></code></blockquote>

<h4>Nested arrays</h4>
Structures with nested arrays require an explicit constructor to ensure the
structure size is properly calculated.
<blockquote><code><pre>
typedef struct _Buffer {
  char buf1[32];
  char buf2[1024];
} Buffer;

class Buffer extends Structure {
  public byte[] buf1 = new byte[32];
  public byte[] buf2 = new byte[1024];
}
</pre></code></blockquote>

Calculation of the native size of the structure is deferred until the
structure is actually used.

<h4>Variable-sized structures</h4>
Structures with variable size, or with primitive array elements, for example:<br>
<blockquote><code><pre>
// Original C code
typedef struct _Header {
  int flags;
  int buf_length;
  char buffer[1];
} Header;
</pre></code></blockquote>

require a constructor which establishes the required size for the structure
and initializes things appropriately.  For example:<br>

<blockquote><code><pre>
// Equivalent JNA mapping
class Header extends Structure {
  public int flags;
  public int buf_length;
  public byte[] buffer;
  public Header(int bufferSize) {
    buffer = new byte[bufferSize];
    buf_length = buffer.length;
    allocateMemory();
  }
}
</pre></code></blockquote>

<h4>Volatile fields</h4>
Normally, JNA will write the entire contents of a <code>Structure</code> prior
to a function call and read back from native memory after the function call.
Sometimes a structure field is not intended for client use, gets modified
asynchronously by hardware, or otherwise is effectively read-only.
If you expect any fields of the structure to be modified by any agent outside
your Java program, you should mark the field <code>volatile</code>.  This
prevents JNA from automatically updating the native memory from the Java
value.  You can still force an update of the native memory from the Java value
by calling {@link com.sun.jna.Structure#writeField(String)} for the field in
question. 
<blockquote><code><pre>
class Data extends com.sun.jna.Structure {
  public volatile int refCount;
  public int value;
}
...
Data data = new Data();
</pre></code></blockquote>
In the above example, the field <code>refCount</code> will only be written
to native memory based on the Java value with a call to
<code>data.writeField("refCount")</code>.  To obtain the current state of
native memory, call {@link com.sun.jna.Structure#read()} (to update the entire
structure) or {@link com.sun.jna.Structure#readField(String)
data.readField("refCount")} (to update just the <code>refCount</code> field). 

<h4>Read-only fields</h4>
If you want to absolutely prevent Java code from modifying
a <code>Structure</code>'s contents, you may mark its
fields <code>final</code>.  Structure reads can still overwrite the values
based on native memory contents, but no Java code will be able to modify any
of the fields.
<blockquote><code><pre>
class ReadOnly extends com.sun.jna.Structure {
  // Do not initialize the field here, or the compiler will inline the value!
  public final int refCount;
  {
    // Initialize fields here, to ensure the values are not inlined
    refCount = -1;
    read();
    // refCount might now have a different value
  }
}
...
ReadOnly ro = new ReadOnly();
// Will not compile!
ro.refCount = 0;
</pre></code></blockquote>

Make certain you attend to the following:
<ol>
<li>All final fields should be initialized in the constructor.
<li>If you call Structure.read() from anywhere but the constructor, keep in
  mind that the compiler and/or hotspot will be assuming field values will not
  change across that function call.
</ol>

<a name="unions"></a>
<h3>Unions</h3>
Unions are a special type of Structure.  Each declared field within the union
overlays the same space in native memory.  When writing a union to native
memory, you <em>must</em> specify which field is to be written by supplying
the desired field's class to the {@link com.sun.jna.Union#setType}
method.  On read, all non-pointer-based fields will be initialized from native
memory.  Structure, String, and WString members will <em>not</em> be
initialized unless they are selected via {@link com.sun.jna.Union#setType}.

<a name="last-error"></a>
<h3>Obtaining "last" error</h3>
If a function sets the system error property
(<code><a href="http://www.opengroup.org/onlinepubs/009695399/functions/errno.html">errno</a></code> or 
<code><a href="http://msdn.microsoft.com/en-us/library/ms679360(VS.85).aspx">GetLastError()</a></code>), 
the error code will be thrown as a {@link com.sun.jna.LastErrorException} if you 
declare the exception in your JNA mapping. Alternatively, you can use 
{@link com.sun.jna.Native#getLastError()} to retrieve it. Throwing an exception
is preferred since it has better performance.

<a name="java-objects"></a>
<h3>Arbitrary Java Object arguments/return values</h3>
In some cases, such as invoking native VM functions directly, it is necessary
to pass Java objects to the native methods.  By default, JNA disallows using
any Java object that is not explicitly supported unless it derives from
{@link com.sun.jna.NativeMapped}, because it is generally unnecessary to use
such objects and usually signals a programmer error.  To avoid errors flagging
the use of Java objects, use the library load option {@link
com.sun.jna.Library#OPTION_ALLOW_OBJECTS} with Boolean.TRUE.
<p>
<a href="#toc">Table of Contents</a>
<a name="invocation-mapping"></a>
<h2>Invocation Mapping</h2>
Sometimes native functions exist only as C preprocessor macros or as inline functions.  If you need to do more than simply change the name of the invoked function (which can be handled via <a href="#function-mapping">Function Mapping</a>), an {@link com.sun.jna.InvocationMapper} allows you to arbitrarily reconfigure the function invocation, including changing the method name and reordering, adding, or removing arguments.  See the {@link com.sun.jna.InvocationMapper} documentation for details.

<p>
<a href="#toc">Table of Contents</a>
<a name="global-data"></a>
<h2>Library Global Data</h2>
The method {@link com.sun.jna.NativeLibrary#getGlobalVariableAddress} may be used to obtain the address of global variables as a {@link com.sun.jna.Pointer}.  Pointer methods may then be used to read or write the value as appropriate for the variable type.

<p>
<a href="#toc">Table of Contents</a>
<a name="crash-protection"></a>
<h2>VM Crash Protection</h2>
It is not uncommon when defining a new library and writing tests to encounter memory access errors which crash the VM.  These are often caused by improper mappings or invalid arguments passed to the native library.  To generate Java errors instead of crashing the VM, call <code>{@link com.sun.jna.Native#setProtected Native.setProtected(true)}</code>.  Not all platforms support this protection; if not, the value of {@link com.sun.jna.Native#isProtected} will remain <code>false</code>.<p>
NOTE: When protected mode is enabled, you should make use of the jsig library, if available (see <a href="http://download.oracle.com/javase/6/docs/technotes/guides/vm/signal-chaining.html">Signal Chaining</a>) to avoid interfering with the JVM's use of signals.  In short, set the environment variable <code>LD_PRELOAD</code> (or <code>LD_PRELOAD_64</code>) to the path to <code>libjsig.so</code> in your JRE lib directory (usually ${java.home}/lib/${os.arch}/libjsig.so) before launching your Java application.
 

<p>
<a href="#toc">Table of Contents</a>
<a name="performance"></a>
<h2>Performance</h2>
<h3>Use direct mapping of methods</h3>
Using <a href="#direct-mapping">direct mapping</a> of methods makes native
calls more efficiently than does interface mapping.  Direct mapping does not
support varargs calls or arrays of Pointer, String, or WString as an argument
or return value.  For optimium results, use only primitive arguments and
return values; you'll have to convert to and from objects yourself explicitly.
<h3>Avoid type mapping</h3>
Type mapping incurs additional overhead on each function call.  You can avoid
this by ensuring that your arguments and/or return types are already primitive
types.
<h3>Pointer/Array/Buffer Variants</h3>
Java primitive arrays are generally slower to use than direct memory
(Pointer, Memory, or ByReference) or NIO buffers, since the Java memory has to
be pinned and possibly copied across the native call, since the Java array is not necessarily contiguously allocated.
<h3>Large Structures</h3>
Structures are normally written to native memory before and read back from
native memory after a function call.  With very large structures, there can be
a performance hit using reflection to walk through all the fields.  Structure
auto-synch can be disabled by calling
{@link com.sun.jna.Structure#setAutoSynch} with a <code>false</code> parameter.
It is then up to you to use {@link com.sun.jna.Structure#readField(String)}
and {@link com.sun.jna.Structure#writeField(String)} or {@link
com.sun.jna.Structure#writeField(String,Object)} to synch with just the fields
of interest. 
<h3>Throw exceptions on last error</h3>
In those methods where you are interested in the value of errno/GetLastError(),
declare your method to throw {@link com.sun.jna.LastErrorException}.
</body>
</html>
